The Debug build of OpenDoc™ (see "Read Me - Debug Build" in this folder) includes a menu called "ODDebug", which appears just below the "About..." command in the Apple menu. This menu includes commands that let you access a number of cool debugging features.
HEAP INFO
Displays an alert with information on the memory usage of the OpenDoc heap (which lives in temporary memory) and the application heap.
MEMORY VALIDATION
Toggles the validation mode of the OpenDoc memory manager; this is normally on in the debug build. In this mode parameters to memory manager calls are sanity-checked. It also fills blocks with hex "BBBB" when they are created, and "DDDD" after they're disposed, to help track down errors where you reference storage that's either uninitialized or disposed. This slows things down somewhat, but not really noticeably. There should be little reason to turn it off.
HEAP CHECKING
This is an intense version of memory validation. On every memory manager call, the entire heap is scanned to make sure it has not been corrupted. This will slow OpenDoc down by an order of magnitude or so, so you don't want to turn it on unless it's absolutely necessary. But it can be very useful in catching strange memory-trashing bugs. (You can also turn this on programmatically; see the "Memory Manager" tech note in the Tech Notes folder on this CD.
LEAK DETECTION
Helps detect memory leaks in the OpenDoc heap, in a manner similar to the venerable 'leaks' dcmd for MacsBug. How to use it:
1. First turn on logging.
2. Choose "Leak Detection" from the ODDebug menu.
3. Perform an operation (e.g. activating and deactivating your part) three or more times in a row. It has to be an operation involving this document, and it can't involve closing the document. Nearly anything else goes.
4. Choose "Leak Detection" again to turn off this mode.
5. A list of stack crawls representing allocations of blocks that were never disposed will be written to the log. Only situations that occurred three or more times will be shown, so as not to show one-time allocations that might represent some kind of caching.
This command will not detect memory leaks in the application heap. You can use the regular 'leaks' dcmd (available on the developer Tool Chest CD) to do that.
EAT MEMORY
Allocates a 32k handle in the application heap every time this command is chosen. If you do this enough times, you'll run the heap out of memory, which is useful in checking how well things work in low-memory situations. (Remember that most OpenDoc memory allocation should take place in the OpenDoc heap, which lives in temporary memory, not the application heap. See the "Memory Etiquette" tech note.)
PURGE
Calls Purge( ) on the global ODSession object, which in turn tells most other OpenDoc objects (including all parts) to purge. This is useful in debugging low-memory behavior, including your part's Purge method.
LOG TO STDOUT FILE
Turns on logging, with the destination being a file called "stdout", usually in the same folder as the open document. If there is already a file called "stdout", the new one will be called "stdout1", et cetera.
The output written to the log comes from somPrintf( ) statements. This is a standard System Object Model™ (SOM) function that is called the same way as normal printf. You can call it yourself to have your part write info to the log; this is a useful last-ditch debugging tool. (A useful variant is the PRINT() macro defined in ODDebug.h, which does not generate any code if you compile your part with ODDebug=0.) Various parts of OpenDoc also write to the log. In particular, when an exception is thrown a stack crawl and the error number will be written to the log.
To turn off logging, choose this command again.
LOG TO DEBUGWINDOW
Turns on logging (see above) but directs output to the DebugWindow app, which is supplied on this CD. Launch the app before you turn logging on. This is handy in that it lets you watch the log statements appear as they happen. However, it's a lot slower than writing to the stdout file.
GENERATE DEBUGSTRS
Turns on logging (see above) but displays the output by calling DebugStr. This is generally pretty annoying but can occasionally be useful.
DUMP ODOBJECTS
Available only when logging is turned on. This command searches the OpenDoc heap for SOM objects and writes the location, size and class name of each one to the log.
BREAK ON THROW
This is a toggle switch; when on, any exceptions thrown by OpenDoc itself (not by parts, other than the engineering test parts such as Container) will cause a WARNing DebugStr. This is a very useful way to find out where an exception thrown by OpenDoc is coming from.
You can programmatically enable this behavior in your own part (if you use the Except utility) by calling SetBreakOnThrow, declared in Except.h.
SOM TRACE
Turns on SOM trace mode, in which every SOM method call — in OpenDoc or a part — causes a line describing the function to be written to the log.
